---
title: Graphics Context
slug: /graphics-context
section: Graphics
---

## Why Graphics?

[[ExcaliburGraphicsContext]] is the abstraction over the underlying drawing mechanism used to displaying images and graphics to the screen. It is recommended to use [ex.Graphics](/docs/graphics) objects with [[Actors]]/[[Entities]] but the [[ExcaliburGraphicsContext]] can be directly drawn to.

The default implementation in Excalibur uses WebGL, however Excalibur can fallback to the 2D Canvas implementation if WebGL isn't supported or there isn't browser hardware acceleration. [Read more](#performance)

```mermaid mermaid
sequenceDiagram
    participant Entity
    participant Engine
    participant ExcaliburGraphicsContext
    participant RenderPlugin
    loop Current Frame Draws
    Entity ->> ExcaliburGraphicsContext: draw(renderer, ...params)
    ExcaliburGraphicsContext ->> Draw Call Pool: 
    Draw Call Pool ->> ExcaliburGraphicsContext: Batch Call
    Note right of Draw Call Pool: Captures current state/transform/renderer
    end
    Engine ->> ExcaliburGraphicsContext: End of Frame flush() 
    Note right of ExcaliburGraphicsContext: Sort Draw Calls By Z
    loop flush() Every Draw Call
        ExcaliburGraphicsContext ->> RenderPlugin: Renderer.draw(params)
        Note right of RenderPlugin: Build up buffers for GPU
        alt Renderer Switch/Batch Full
            RenderPlugin ->> RenderTarget: flush() Batch Draw
        end
        loop Every Post Process
            RenderTarget ->> RenderTarget: Post Process 
        end
        RenderTarget ->> Screen: blit()
    end



```

### Canvas support

If you have need to switch to 2D canvas based rendering turn on the flag before engine construction.

:::warning

<div>

Some features like

<a href="#custom-renderer">

custom renderers

</a>

and

<a href="/docs/postprocessors">

post processors

</a>

do not work with the Canvas 2D implementation!

</div>

:::

```typescript
ex.Flags.useCanvasGraphicsContext();
const game = new ex.Engine(...);
```

## Drawing to the Context

The graphics context automatically batches draw calls and flushes them to the screen at the end of every frame. It is therefore recommended you draw in one of the supported drawing lifecycle events.

Either directly by extending the Excalibur Scene

```typescript
const game = new ex.Engine({...});
class MyScene extends ex.Scene {
    onPreDraw(ctx: ExcaliburGraphicsContext) {
        ctx.save();
        ctx.drawRectangle(...);
        ctx.restore();
    }
    onPostDraw(ctx: ExcaliburGraphicsContext) {
        ctx.save();
        ctx.drawRectangle(...);
        ctx.restore();
    }
}
game.addScene('myscene', new MyScene());
game.goToScene('myscene');
game.start();
```

Or as an event on the the Excalibur Scene

```typescript
const game = new ex.Engine({...});
game.currentScene.on('predraw', (ctx: ExcaliburGraphicsContext) => {
    ctx.save();
    ctx.drawRectangle(...);
    ctx.restore();
});
```

Or as part of an Actor/Entity graphics component

```typescript
const game = new ex.Engine({...});
const actor = new ex.Actor({pos: ex.vec(100, 100)});
game.currentScene.add(actor);
game.start();

// Draw before graphics component but after the transform for actor pos/rotation/scale
actor.graphics.onPreDraw = (ctx: ExcaliburGraphicsContext) => {

    ctx.save();
    ctx.drawRectangle(...);
    ctx.restore();
}

// Draw after graphics component but after the transform for actor pos/rotation/scale
actor.graphics.onPostDraw = (ctx: ExcaliburGraphicsContext) => {

    ctx.save();
    ctx.drawRectangle(...);
    ctx.restore();
}

```

## Save and Restore

The [[ExcaliburGraphicsContext]] emulates other graphics context APIs by providing a save/restore feature. These are used to save the state of the context before you modify its global state, and then restore it back after you are finished drawing. If you do not, modifications to [[ExcaliburGraphicsContext]] will affect other draw calls.

```typescript
onPostDraw(ctx: ExcaliburGraphicsContext) {
    ctx.save();
    ctx.translate(50, 50);
    ctx.rotate(Math.PI / 2);
    ctx.drawRectangle(...);
    ctx.restore();
}
```

## Setting z-index

Excalibur allows you to set the z-index of any draw call by setting the [[ExcaliburGraphicsContext.z]] property on the context.

```typescript
onPostDraw(ctx: ExcaliburGraphicsContext) {
    ctx.save();
    ctx.z = -1;
    ctx.drawRectangle(...);
    ctx.restore();
}
```

## Snap To pixel

Excalibur has built in snap to pixel support, this can be useful if you are building a game with a pixel aesthetic.

To enable snap to pixel, enable `snapToPixel` in the engine constructor parameter. By default `snapToPixel` is not enabled.

```typescript
const game = new ex.Engine({
    ...
    snapToPixel: true
});
```

## Custom Renderer

Custom renderers are a way to extend what the [[ExcaliburGraphicsContextWebGL]] can draw by default. In fact all of the things that the graphics context can draw are implemented this way internally.

```typescript

const MyRenderer implements ex.RendererPlugin {
    ...
}

const graphicsContextWebGL = game.graphicsContext as ExcaliburGraphicsContextWebGL;
graphicsContextWebGL.register(new MyRenderer());

graphicsContextWebGL.draw<MyRenderer>(...);

```

Read a more in-depth example [here](/docs/custom-renderer-plugins)

## Performance

Excalibur's performance fallback behavior can be configured by developers to help players experiencing poor performance in non-standard browser configurations

This will fallback to the Canvas2D rendering graphics context which usually performs better on non hardware accelerated browsers, currently postprocessing effects are unavailable in this fallback.

By default if a game is running at 20fps or lower for 100 frames or more after the game has started it will be triggered, the developer can optionally show a player message that is off by default.

```typescript
var game = new ex.Engine({
    ...
    configurePerformanceCanvas2DFallback: {
        // opt-out of the fallback
        allow: true,
        // opt-in to a player pop-up message
        showPlayerMessage: true,
        // configure the threshold to trigger the fallback
        threshold: { fps: 20, numberOfFrames: 100 }
    }
});
```
